As mentioned in the previous section, some components only provide support for additional file formats, and don’t expose any API functions, and some components provide additional API. If your application uses a component that provides additional API functions, there are a few additional steps needed to use these API functions.
There are two ways that the application can call a function implemented by the component. The first method is calling a component’s API functions via a component manager function:
 Copy Code |
|
|---|---|
IG_comm_function_call(LPCHAR lpEntryName, ... ); |
|
where lpEntryName is a name of the requested function in the form "<COMP_NAME>.<FUNC_NAME>", where <COMP_NAME> is a name of the component that provides the function, and <FUNC_NAME> is the name of the function.
To simplify the calling of component functions, all components provide special macros for each of their public functions. This macro is located in the header file i_<COMP_NAME>.h for each component. For instance, i_CLN.h for ImageClean component:
| Copy Code |
|
|---|---|
#define IG_IC_clean_borders_ex( hIGear, nLeftBorderSize, nRightBorderSize, nTopBorderSize, nBottomBorderSize, nMinLinesNum, nMinLineWidth) ((AT_ERRCOUNT (CACCUAPI *)(LPCHAR, HIGEAR, UINT, UINT, UINT, UINT, UINT, UINT)) IG_comm_function_call)("CLN.IG_IC_clean_borders_ex", hIGear, nLeftBorderSize, nRightBorderSize, nTopBorderSize, nBottomBorderSize, nMinLinesNum, nMinLineWidth) |
|
With the use of this macro, a call to a component function looks exactly like a call to a regular C function:
| Copy Code |
|
|---|---|
#include "i_CLN.h"
…
IG_IC_clean_borders_ex( hIGear, nLeftBorderSize, nRightBorderSize,
nTopBorderSize, nBottomBorderSize, nMinLinesNum, nMinLineWidth);
|
|
Another method is to obtain a pointer to the component function and then call this function via its pointer. Use the following function to obtain a component function pointer:
| Copy Code |
|
|---|---|
IG_comm_entry_request(
LPCHAR lpEntryName,
LPAFT_ANY *lpFuncPtr,
LPCHAR lpReason
);
|
|
- The first parameter is the name of the function in the format described above.
- The second parameter is a pointer a variable of type LPAFT_ANY, which will be overwritten with the pointer to the necessary function.
- The third parameter is a text description reason to get access for this function (it is optional and can be NULL).
The component public header contains a type declaration for all its public functions. The correct way to call such a function would be to declare the variable of the necessary function type defined in the component’s public header; use IG_comm_entry_request() to initialize this variable with the correct value and then call it.
Calling component API functions by their pointers provides better performance, because it avoids the overhead of finding a function pointer by its name. If your application does not call component functions repeatedly in time-critical routines, you can use the simple method of calling component functions via their macros.